package timbap.visualizer.api.context.playlist;

import timbap.visualizer.api.context.Configuration;
import timbap.visualizer.api.exceptions.NoPlaylistSelectedException;
import timbap.visualizer.api.exceptions.PlaylistParserException;
import timbap.visualizer.api.model.PlaylistEntry;

import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.util.List;

/**
 * The <code>PlaylistManager</code> is responsible for
 * selecting a playlist file, parsing it and providing
 * access to the playlist entries.
 *
 * @author  Andreas Pabst
 * @see     timbap.visualizer.api.model.PlaylistEntry
 */
public interface PlaylistManager {
    
    /**
     * initializes the playlist manager from a given
     * timbap configuration.
     * 
     * @param pCfg	the timbap configuration to use
     * @throws NoPlaylistSelectedException ...
     * @throws PlaylistParserException ...
     */
    public void init(Configuration pCfg)
            throws NoPlaylistSelectedException, PlaylistParserException;

    /**
     * retrieves the playlist chooser used
     * @return the playlist chooser
     */
    public PlaylistChooser getPlaylistChooser();

    /**
     * sets the playlist chooser to use
     * @param pPlaylistChooser the playlist chooser to use
     */
    public void setPlaylistChooser(PlaylistChooser pPlaylistChooser); 

    /**
     * parses a playlist file and returns the extracted
     * list of playlist entries.
     * 
     * @param pPlaylistFile	the playlist file to parse
     * @return	the parsed playlist
     * @throws IOException ...
     * @throws PlaylistParserException ...
     */
    public List<PlaylistEntry> parsePlaylist(File pPlaylistFile)
            throws IOException, PlaylistParserException;
    
    /**
     * gets the playlist
     * 
     * @return	the playlist
     */
    public List<PlaylistEntry> getPlaylist();
    
    /**
     * sets the playlist
     * 
     * @param playlist	the playlist to set
     */
    public void setPlaylist(List<PlaylistEntry> playlist);

    /**
     * determines the number entries in the playlist
     * 
     * @return	the number of entries in the playlist
     */
    public int getPlaylistSize();

    /**
     * gets the playlist entry at the specified position
     * 
     * @param i	the position index
     * @return	the playlist entry at the specified position
     */
    public PlaylistEntry getPlaylistEntry(int i);

    /**
     * finds a playlist entry matching the specified URI
     * 
     * @param pUri	the file URI to search for
     * @return		the matching playlist entry or null if none matches
     */
    public PlaylistEntry findPlaylistEntry(URI pUri); 

}
